﻿========================================================================
  戸籍管理システム Web版  Version 1.1.1
========================================================================

  ソフト名     : 戸籍管理システム Web版
  バージョン   : 1.1.1
  作 者        : highdefinitionaudiodriver
  動作環境     : Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+) / Node.js 20 以上
  ライセンス   : MIT License（フリーソフト／オープンソース）
  種 別        : フリーソフト
  作成日       : 2026-06-04

------------------------------------------------------------------------
■ ソフトの説明 / 使用方法（README より）
------------------------------------------------------------------------

戸籍情報システム Web版

> 自治体システム標準化・ガバメントクラウド利用を見据えた、ChromeOS Flex でも動作する Webアプリケーションの設計・実装リファレンスです。


⚠️ 本リポジトリは AI協働（Claude Code ⇔ Codex）による設計・実装途中のリファレンスです。
本番自治体システムとしての実利用を意図したものではありません。標準仕様準拠、ガバメントクラウド適合、セキュリティ監査、個人情報保護評価は別途必要です。

---

これは何？（30秒で）

- 誰のため：自治体情報システム担当者、自治体標準化対応のSIベンダー、ChromeOS Flex 等の低コスト端末で動く基幹業務Web化を検討する開発者
- 何を扱うか：戸籍届出、記載、証明、附帯事務、外字、オンライン連携を扱います。
- 何があるか：設計書由来の機能・画面・帳票・APIカタログ、Node.js標準ライブラリのみで動くAPI/Web UI、RBAC、支援措置マスク、監査ログ、EUC二人承認、帳票HTMLプレビュー
- 使う条件：Node.js 20+。インフラ検証では Docker / PostgreSQL 16 / Keycloak を利用

何を解いているか

このリポジトリは、自治体基幹業務をブラウザのみで扱うための最小実装を提供します。

- 標準仕様書・設計書Excelを apps/api/data/catalog.json に取り込み、機能・画面・帳票・APIを追跡可能にする
- docs/openapi.yaml をAPIカタログのSSOTとして扱い、npm run check でドリフトを検出する
- 支援措置・抑止対象レコードをAPIレイヤでマスクする
- EUC抽出は機微情報を含む場合に二人承認へ昇格し、CSVダウンロードまで確認する
- 帳票は現段階ではHTMLプレビューを返し、PDFテンプレート実装へ拡張可能にする
- OIDC/Keycloak、PostgreSQL/Flyway、ガバメントクラウド利用を想定した基盤ファイルを置く

アーキテクチャ


Browser (ChromeOS Flex / Chrome / Edge)
  └─ apps/web        Vanilla JS SPA
       │ fetch
       ▼
apps/api/server.mjs  Node.js API
  ├─ catalog.json    設計書由来カタログ
  ├─ records         業務レコードCRUD
  ├─ restrictions    支援措置・抑止マスク
  ├─ audit           監査ログ
  ├─ reports         HTML帳票プレビュー
  └─ euc             EUC抽出・二人承認・CSV出力
       │ planned
       ▼
PostgreSQL 16 + Flyway / Keycloak (infra/)


実装状況

| 観点 | 状況 |
|---|---:|
| 機能カタログ | 169 件 |
| 画面カタログ | 30 件 |
| 帳票カタログ | 25 件 |
| APIカタログ | 20 件 |
| 外部連携カタログ | 10 件 |
| Node API / Web UI | 実装済み（開発・検証用） |
| 認証（パスワード/2FA/ロック） | 実装済み |
| RBAC / 支援措置マスク | 実装済み |
| 監査ログ（機能ID・操作端末） | 実装済み |
| 電子公印 / コードマスタ管理 | 実装済み |
| EUC二人承認 / CSV出力 | 実装済み |
| 帳票プレビュー（公印・発行番号） | 実装済み |
| OIDC / Keycloak | 足場あり |
| PostgreSQL / Flyway | 足場あり |
| テスト | node --test 14/14 PASS |

クイックスタート

必要環境

- 推奨動作スペック:
  - 開発・サーバー実行環境:
    - CPU: 2コア/4スレッド以上のx86-64またはARM64プロセッサ (Core i3以上推奨)
    - メモリ: 8GB RAM以上 (DockerやPostgreSQLなどのデータベースコンテナ同時起動時)
    - ストレージ: SSD 10GB以上の空き容量
    - OS: Windows 10/11, macOS, Linux (Ubuntu 20.04+)
  - クライアント・ブラウザ環境 (ChromeOS Flex等):
    - CPU: Intel Celeron / Core i3 相当以上
    - メモリ: 4GB RAM以上
    - ブラウザ: Google Chrome (最新版推奨), Microsoft Edge (最新版)
    - 画面解像度: 1366x768 以上 (1920x1080 推奨)

- Node.js 20+
- npm
- Docker Desktop（PostgreSQL / Keycloak を試す場合）

起動


cd C:/Users/highd/Documents/Github/koseki-web
npm start
http://localhost:4173 を開く


ポートを変える場合:


$env:PORT=4280
npm start


テスト


npm test
npm run check


OpenAPIカタログ再生成


npm run catalog:apis



PostgreSQL + Flyway ワンコマンド起動


PostgreSQL 起動 → マイグレーション適用 → サーバー起動 (DATABASE_URL付き)
npm run dev:full


| コマンド | 説明 |
|---|---|
| npm run db:up | PostgreSQL コンテナ起動 |
| npm run db:migrate | Flyway でマイグレーション適用 |
| npm run db:stop | 全コンテナ停止 |
| npm run db:logs | コンテナログをフォロー |
| npm run db:reset | コンテナ削除 → 再起動 → 再マイグレーション |

PostgreSQL / Keycloak ローカル基盤


cd infra
docker compose up -d


Keycloak管理画面: http://localhost:8080  
初期管理ユーザー: admin / admin

ディレクトリ構成


.
├── apps/
│   ├── api/                  # Node.js API と runtime JSON
│   └── web/                  # ブラウザUI
├── docs/
│   ├── openapi.yaml          # OpenAPI 3.1 SSOT
│   └── juki-reference-alignment.md
├── infra/
│   ├── docker-compose.yml    # PostgreSQL / Keycloak ローカル基盤
│   ├── keycloak/             # realm/client/role 初期定義
│   ├── migrations/           # Flyway形式DDL足場
│   └── schema.sql            # 現行DDL
├── tests/                    # Node test スモーク / RBAC / EUC / 帳票
├── tools/                    # OpenAPI → catalog 同期ツール
├── CLAUDE_CODE_HANDOFF.md    # Codex/Claude Code 引き継ぎ
├── README_IMPLEMENTATION.md  # 実装メモ
└── README.md                 # 本ファイル


設計成果物

| ファイル | 内容 |
|---|---|
| 戸籍情報システムWeb版_基本設計書_v0.1.xlsx | 設計書Excel |
| apps/api/data/catalog.json | 設計書由来の機能・画面・帳票・APIカタログ |
| docs/openapi.yaml | API仕様のSSOT |
| infra/schema.sql | PostgreSQL DDL足場 |
| infra/migrations/ | Flyway形式のマイグレーション足場 |
| CLAUDE_CODE_HANDOFF.md | Claude Code / Codex 間の引き継ぎ |

主要API

共通基盤

| API | 内容 |
|---|---|
| GET /health, GET /api/health | ヘルスチェック（DB状態・uptime・version） |
| GET /api/catalog, GET /api/catalog/{section} | 設計カタログ照会・検索 |
| GET/POST /api/records, /api/records/{domain}/{id} | 業務レコード共通API（CRUD・ページネーション・検索） |
| GET/POST/DELETE /api/restrictions | 支援措置・抑止設定 |
| GET /api/audit | 監査ログ（機能ID・操作端末・ページネーション） |
| POST /api/reports/{reportId}/preview / GET /api/reports/jobs/{jobId}/download | 帳票プレビュー作成・取得（電子公印/発行番号付き） |
| POST /api/euc/query / POST /api/euc/{jobId}/approve / GET /api/euc/jobs/{jobId}/download | EUC抽出・二人承認・CSV出力 |
| GET /api/events | SSE リアルタイム通知 |

認証・アカウント管理（AUTH_MODE=password）

| API | 内容 |
|---|---|
| POST /api/auth/login | パスワード認証（5回失敗ロック・TOTP二要素認証） |
| GET /api/auth/policy | パスワードポリシー公開 |
| POST /api/auth/register | ユーザー登録（ADMIN） |
| POST /api/auth/change-password | パスワード変更 |
| POST /api/auth/2fa/setup, /enable, /disable | TOTP二要素認証の登録・有効化・解除 |
| GET /api/auth/users, POST /api/auth/users/{id}/unlock | ユーザー管理・ロック解除（ADMIN） |

電子公印・コードマスタ管理

| API | 内容 |
|---|---|
| GET/POST /api/official-seals, /api/official-seals/{id} | 電子公印マスタ管理（支所単位・適用期間・帳票印字） |
| GET/POST /api/masters/{type}, /api/masters/{type}/{id} | 汎用コードマスタ CRUD |
| GET /api/masters/{type}/export.csv, POST /api/masters/{type}/import | コードマスタ CSV 一括入出力 |

ドメイン固有API（業務エンティティ）は docs/openapi.yaml を参照。

セキュリティ方針

- 認証モード AUTH_MODE: local（開発・ヘッダ偽装）/ password（ID+PW+TOTP二要素認証）/ oidc（Keycloak JWT/JWKS）
- パスワードポリシー: 8文字以上・英数字混在・90日有効期限（環境変数で調整可）
- アカウントロック: 認証失敗5回でロック（デジタル庁 0390050）
- 二要素認証: TOTP（RFC 6238）対応
- 支援措置・抑止: SUPPORT_ACCESS ロールなしでは詳細をマスク（ADMIN も自動付与されない）
- 監査ログ: 操作者・機能ID・操作端末・日時を append-only NDJSON で記録
- クライアント送信の x-user-roles は ALLOW_DEV_HEADERS=true の明示時のみ採用
- セキュリティヘッダ（CSP / X-Frame-Options / Referrer-Policy / HSTS 等）を返却

出典・準拠方針

- デジタル庁「地方公共団体の基幹業務システムの統一・標準化」方針を参照
- GCAS / ガバメントクラウド利用方針を参照
- ただし現時点では、標準適合認定・GCAS適合・本番運用可否を保証するものではありません

AI協働の記録

本リポジトリは Claude Code と Codex の協働で設計・実装を継続しています。主な引き継ぎ・レビュー資料:

- CLAUDE_CODE_HANDOFF.md
- HANDOFF_FOR_CODEX.md
- docs/juki-reference-alignment.md
- docs/openapi.yaml

ライセンス・利用上の注意

学習・検証・設計参考用途のリファレンス実装です。実際の自治体業務で利用する場合は、標準仕様への逐条適合確認、セキュリティ設計、個人情報保護評価、運用設計、監査、バックアップ、DR、調達要件を別途実施してください。

<!-- CURRENT-STATUS:START -->
最新実装状況（2026-06-02 更新）

実装済み機能

| カテゴリ | 機能 | 状態 |
|---|---|---|
| API基盤 | ドメインREST CRUD（一覧/詳細/登録/編集/削除・ページネーション・検索） | ✅ |
| DB hybrid | PostgreSQL + JSON fallback（COUNT(*) OVER() 1クエリ・ページネーション） | ✅ |
| 認証 | パスワード(PBKDF2)・TOTP二要素認証・アカウントロック・パスワードポリシー | ✅ |
| RBAC / 支援措置 | ロールベース認可・支援措置マスク（SUPPORT_ACCESS 明示付与） | ✅ |
| 監査 | append-only NDJSON（機能ID・操作端末・日時・操作者） | ✅ |
| 電子公印 | 公印マスタ管理・帳票印字（発行年月日/発行番号/（公印省略）） | ✅ |
| コードマスタ | 汎用マスタ CRUD・CSV 一括入出力（UTF-8 BOM） | ✅ |
| EUC | 二人承認ワークフロー・CSV出力・SSE通知 | ✅ |
| セキュリティ | X-Request-ID, CORS, レートリミット, ボディサイズ制限, CSP/HSTS | ✅ |
| フロントエンド | 検索・ソート・ページネーション・CSV出力・インライン編集・詳細展開 | ✅ |
| テスト | node --test 14/14 PASS（HTTP e2e: 認証/公印/マスタ/監査 等） | ✅ |

環境変数一覧

| 変数名 | デフォルト | 説明 |
|---|---|---|
| PORT | 4173 | APIサーバーポート |
| NODE_ENV | development | production で HSTS ヘッダー付与 |
| DATABASE_URL | （未設定） | PostgreSQL接続文字列（未設定時は JSON フォールバック） |
| AUTH_MODE | local | local / password / oidc |
| PW_MIN_LENGTH / PW_MAX_AGE_DAYS / MAX_FAILED_ATTEMPTS / LOCK_DURATION_MIN | 8 / 90 / 5 / 30 | パスワードポリシー（AUTH_MODE=password） |
| SESSION_SECRET | （要変更） | セッション署名鍵（本番では必ず変更） |
| CORS_ORIGIN | （空） | フロントエンドオリジン（空で無効） |
| RATE_LIMIT / RATE_LIMIT_POST | 200 / 20 | IPあたり1分間のリクエスト上限 |
| REPORT_FORMAT / CHROME_PATH | html | pdf 指定で Puppeteer による PDF 出力 |
| ALLOW_DEV_HEADERS | false | true で x-user-roles ヘッダーによるロール強制（検証用） |

> 共通コア（apps/api/db.mjs / auth.mjs / credentials.mjs）は全20システムで共有。
> 同期検証は Github ルートの tools/verify-shared-core.mjs、版管理は SHARED_CORE.md を参照。

_最終更新: 2026-06-02 by Claude Code_
<!-- CURRENT-STATUS:END -->

------------------------------------------------------------------------
■ 動作環境
------------------------------------------------------------------------
  Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+) / Node.js 20 以上
  ※ オンライン専用ソフトではありません（ローカル環境で動作します）。

------------------------------------------------------------------------
■ インストール / アンインストール
------------------------------------------------------------------------
  ・本アーカイブを任意のフォルダに展開してください。
  ・詳細な起動手順は上記「ソフトの説明」および同梱の README を参照してください。
  ・アンインストールは展開したフォルダを削除するだけです（レジストリ不使用）。

------------------------------------------------------------------------
■ 転載・再配布について
------------------------------------------------------------------------
  本ソフトは MIT License のオープンソースです。同梱の LICENSE 条文に
  従う限り、自由に利用・改変・再配布できます。
  なお Vector 以外の配布サイトへの無断転載はご遠慮ください。

------------------------------------------------------------------------
■ 免責事項
------------------------------------------------------------------------
  本ソフトの使用によって生じたいかなる損害についても、作者は一切の
  責任を負いません。利用者ご自身の責任においてご使用ください。

------------------------------------------------------------------------
■ 著作権
------------------------------------------------------------------------
  Copyright (c) 2026 highdefinitionaudiodriver
  本ソフトは MIT License の下で公開されています。

------------------------------------------------------------------------
■ 連絡先 / サポート
------------------------------------------------------------------------
  作 者        : highdefinitionaudiodriver
  E-mail       : highdefinitionaudiodriver@gmail.com
  GitHub       : https://github.com/highdefinitionaudiodriver/koseki-web.git
  不具合報告・ご要望は上記 E-mail もしくはリポジトリの Issues へ
  お願いいたします。

========================================================================
